import WebpackLicense from '@components/WebpackLicense';

<WebpackLicense from="https://webpack.js.org/configuration/devtool/" />

# Devtool

Choose a style of source mapping to enhance the debugging process. These values can affect build and rebuild speed dramatically.

Use the [SourceMapDevToolPlugin](/plugins/webpack/source-map-dev-tool-plugin) or [EvalSourceMapDevToolPlugin](/plugins/webpack/eval-source-map-dev-tool-plugin) for a more fine grained configuration.

- **Type:**

```ts
type Devtool = 'string' | false;
```

- **Default:** `cheap-module-source-map` in development mode and `source-map` in production mode

## Configuration guide

### Step 1: determine debugging needs

- **Not required** → Set `devtool: false`
  - Disables all debugging information
  - Zero build overhead with maximum build speed
- **Required** → Proceed to [Step 2](#step-2-define-debugging-requirements)

### Step 2: define debugging requirements

- **Module-level positioning only** → Set `devtool: 'eval'`
  - Each module executed via `eval()` with `//# sourceURL` comment
  - Extremely fast build speed
- **Full source code mapping needed** → Proceed to [Step 3](#step-3-configure-sourcemap)

### Step 3: configure source map

Set `devtool: 'source-map'`, A full source map is emitted as a separate file. It adds a `//# sourceMapURL` comment to the bundle so development tools know where to find it.

It also supports combination with the following modifiers to improve performance and control source map generation.

Performance optimization modifiers, to speed up the build, usually used in development environments:

| Modifier | Effect                                                                                                                                         | Performance improvement |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| eval     | Each module is executed with `eval()` and a source map is added as a DataUrl to the `eval()`, avoiding chunk-level multiple source map concate | ⚡⚡⚡                  |
| cheap    | Maps line numbers only (no columns), ignores source maps from loaders                                                                          | ⚡⚡                    |
| module   | Processes source maps from loaders to map to original code (line-only mapping)                                                                 | ⚡                      |

Functional modifiers, to control source map generation, usually used in production environments:

| Modifier  | Effect                                                                                                                                       |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| hidden    | source map is emitted as a separate file, but no `//# sourceMappingURL=[url]` comment is added to the bundle, protecting source code privacy |
| inline    | source map is added as a DataUrl to the bundle                                                                                               |
| nosources | source map is created without the `sourcesContent` in it                                                                                     |
| debugids  | source map is created with the `debugId` in it                                                                                               |

We expect a certain pattern when validate devtool name, pay attention and don't mix up the sequence of devtool string. The pattern is: `[inline-|hidden-|eval-][nosources-][cheap-[module-]]source-map[-debugids]`.

## Recommended configurations

### Development

The following options are ideal for development:

`eval` - Each module is executed with `eval()` and `//# sourceURL`. This is pretty fast. The main disadvantage is that it doesn't display line numbers correctly since it gets mapped to transpiled code instead of the original code (No source maps from Loaders).

`eval-source-map` - Each module is executed with `eval()` and a source map is added as a DataUrl to the `eval()`. Initially it is slow, but it provides fast rebuild speed and yields real files. Line numbers are correctly mapped since it gets mapped to the original code. It yields the best quality source maps for development.

`eval-cheap-source-map` - Similar to `eval-source-map`, each module is executed with `eval()`. It is "cheap" because it doesn't have column mappings, it only maps line numbers. It ignores source maps from Loaders and only display transpiled code similar to the eval devtool.

`eval-cheap-module-source-map` - Similar to `eval-cheap-source-map`, however, in this case source maps from Loaders are processed for better results. However Loader source maps are simplified to a single mapping per line.

### Production

These options are typically used in production:

'false' - No source map is emitted. This is a good option to start with.

`source-map` - A full source map is emitted as a separate file. It adds a reference comment to the bundle so development tools know where to find it.

`hidden-source-map` - Same as `source-map`, but doesn't add a reference comment to the bundle. Useful if you only want source maps to map error stack traces from error reports, but don't want to expose your source map for the browser development tools.

`nosources-source-map` - A source map is created without the `sourcesContent` (the original source code) in it. It still exposes the original filenames and structure and can be used to map stack traces on the client without exposing the source code. This kind of source map can be deployed to the web server if you can accept the file name being exposed.

:::warning
When using `source-map` or `hidden-source-map`, do not deploy the source maps (`.map` file) to the public web server or CDN. Public source maps will expose your source code and may bring security risks.
:::
